Update example for converting DLC project to benchmark (v2) by niksirbi · Pull Request #49 · neuroinformatics-unit/poseinterface

niksirbi · 2026-05-12T23:06:12Z

Summary

Clean replacement for #40 (Frankenstein branch). Starts fresh from main, builds on top of the now-merged #45 (predictions_to_poseinterface), and adds the gallery example plus supporting utilities and a lightweight test fixture.

The example walks through the following workflow:

Warning

This example specifically documents the DLC-to-poseinterface conversion process. Trying it on other pose estimation software is encouraged, but adaptations will be needed, and the underlying functions are not yet tested on non-DLC inputs. Other source software will be tackled in future PRs.

What's included

frames_to_poseinterface: copies and renames frame images to match the filenames in a framelabels.json (unit tests included).
Lightweight DLC project fixture under tests/data/dlc/MouseTopDown-Loukia-2022-09-13/ : 2 sessions, short MP4 videos, placeholder PNG frames, annotation + prediction CSVs. Used by tests and the gallery example.
convert_dlc_to_benchmark sphinx-gallery example: replacing the old SWC-plusmaze_to_benchmark example. Runs end-to-end against the bundled fixture and demonstrates the full DLC → benchmark conversion (video, framelabels + frame copy, videolabels) followed by clip extraction.
tree utility: for displaying directory structures, used in the example (unit tests included).
movement pin bumped to >=0.16.0 (the version introducing the automatic source-software inference, which predictions_to_poseinterface now relies on).
Docs updates:
- sphinx-gallery execution enabled in conf.py
- API index entries for tree, frames_to_poseinterface, and predictions_to_poseinterface.
- Docs dependencies: jupyter, matplotlib.

Supersedes

Update example for converting DLC project to benchmark #40

How was this tested

I used a variant of this example locally to convert 2 sessions from a 'real' dataset (not just the fixture) and inspect the resulting .json files. The real dataset was structured similarly to the fixture included here.

Checklist

All unit tests pass locally
Pre-commit run
Sphinx-gallery example runs end-to-end (python examples/convert_dlc_to_benchmark.py)
Docs build successfully (make clean html from docs/)
CI passes

How to review

I recommend primarily reviewing the built example end-to-end, and then diving into the newly introduced tree/frames_to_poseinterface functions if/when necessary.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add frames_to_poseinterface utility to copy and rename frame images according to filenames in a COCO JSON file. Also fix the output filename of predictions_to_poseinterface to use _cliplabels.json suffix matching the naming convention. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Adds a minimal DLC project under tests/data/dlc/ with 2 sessions, each containing a small (100 frames) video, placeholder PNGs, and annotation/prediction CSVs. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Replace SWC-plusmaze_to_benchmark example with a new end-to-end example showing how to convert a DLC project to the poseinterface benchmark dataset format. Update sphinx-gallery config to execute examples, add API entries for new functions, and add jupyter and matplotlib dependencies. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

lochhh

Thanks @niksirbi !

I tried the example with a sample dlc project (that has annotations only) and it broke when it tries to find the predictions file. Otherwise the example works as expected. My suggestion is to skip the conversion(s) in the example if the expected files are not found.

It's very nice that we now have a sample DLC project in test data. I'm guessing the broken frame files are intentional, but it would be better to have actual frames, since this would allow us to have images with non-zero width and height in the COCO JSON files. As a follow-up PR, we should consider adding the generated benchmark dataset(s) as part of our test data. These could replace the current "reference dataset" Train/SWC-plusmaze/sub-M708149_ses-20200317/, giving us a more cohesive and internally consistent set of test fixtures (using the sample DLC project as test inputs and the reference dataset as expected outputs) - our current test data comes from a mix of sample inputs/outputs across different projects, along with multiple ad‑hoc fixtures.

Co-authored-by: Chang Huan Lo <changhuanlo@yahoo.com>

Add `import warnings` to io.py (needed after review suggestion introduced `warnings.warn`), update error message match in existing test, and add a new test for the partial-match warning path. Includes minor formatting fixes from ruff-format. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-authored-by: Chang Huan Lo <changhuanlo@yahoo.com>

The write_text() return value (byte count) was rendered as cell output by sphinx-gallery. Use capture_repr = () to suppress it. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Renders `Path | str` instead of `Union[Path, str]` in API docs. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

niksirbi · 2026-05-26T15:38:26Z

Thanks for the review @lochhh and for re-organising the example in a more logical way.

I've accepted your suggestions, except for the ones about test fixtures (we'll tackle these separately as part of #53).

lochhh

Thanks! 🚀

niksirbi marked this pull request as draft May 12, 2026 23:12

This was referenced May 13, 2026

Convert predictions to cliplabels.json using movement #45

Merged

Update example for converting DLC project to benchmark #40

Closed

Proposal: Simplify the project-conversion workflow with a Session-based API #50

Open

niksirbi and others added 10 commits May 18, 2026 16:19

Add tree utility for displaying directory structures

c46b3ab

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add lightweight DLC project fixture for testing and examples

2ebcd68

Adds a minimal DLC project under tests/data/dlc/ with 2 sessions, each containing a small (100 frames) video, placeholder PNGs, and annotation/prediction CSVs. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Pin movement>=0.16.0 and update supported Python versions to 3.12-3.14

271af11

updated conversion example

860d3fe

add workflow image to the conversion example

2eaff04

add API reference entry for predictions_to_poseinterface

a004aa4

Fix predictions_to_poseinterface kwargs in example after rebase

ada238d

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

fix typo

6cfef6b

niksirbi force-pushed the update-dlc-to-coco-example-v2 branch from 99eed8a to 6cfef6b Compare May 18, 2026 15:32

niksirbi and others added 4 commits May 18, 2026 16:52

Rename frames_to_poseinterface params to input_dir/output_dir

533cdd0

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

temporarily try on real data and add provenance

73e0693

switch back to using small fixture in example

f63c209

remove duplicate prediction_to_interface entry in API index

729a09f

niksirbi marked this pull request as ready for review May 19, 2026 10:27

niksirbi requested a review from a team May 19, 2026 10:46

lochhh requested review from lochhh and removed request for a team May 19, 2026 10:52

lochhh requested changes May 22, 2026

View reviewed changes

niksirbi and others added 6 commits May 26, 2026 14:39

Apply suggestions about frames_to_poseinterface

d5f86b4

Co-authored-by: Chang Huan Lo <changhuanlo@yahoo.com>

Apply suggestions about tree

4b86133

Co-authored-by: Chang Huan Lo <changhuanlo@yahoo.com>

Apply suggestions about simplifying tests for tree

638a557

Co-authored-by: Chang Huan Lo <changhuanlo@yahoo.com>

Apply suggestions about gallery example

f6f804f

Co-authored-by: Chang Huan Lo <changhuanlo@yahoo.com>

add myst target for folder structure

a97efdf

niksirbi and others added 2 commits May 26, 2026 15:29

Suppress spurious cell output in provenance example cell

365de7e

The write_text() return value (byte count) was rendered as cell output by sphinx-gallery. Use capture_repr = () to suppress it. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Enable always_use_bars_union for modern union type rendering

238ccda

Renders `Path | str` instead of `Union[Path, str]` in API docs. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

niksirbi mentioned this pull request May 26, 2026

A more cohesive set of test fixtures #53

Open

niksirbi added 2 commits May 26, 2026 16:22

replace image placeholders with real images

7c9c147

add custom example thumbnail

da628f1

niksirbi requested a review from lochhh May 26, 2026 15:38

lochhh approved these changes May 26, 2026

View reviewed changes

lochhh merged commit f3a141c into main May 26, 2026
24 checks passed

lochhh deleted the update-dlc-to-coco-example-v2 branch May 26, 2026 15:53

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update example for converting DLC project to benchmark (v2)#49

Update example for converting DLC project to benchmark (v2)#49
lochhh merged 24 commits into
mainfrom
update-dlc-to-coco-example-v2

niksirbi commented May 12, 2026 •

edited

Loading

Uh oh!

lochhh left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

niksirbi commented May 26, 2026

Uh oh!

lochhh left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

niksirbi commented May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What's included

Supersedes

How was this tested

How to review

Uh oh!

lochhh left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

niksirbi commented May 26, 2026

Uh oh!

lochhh left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

niksirbi commented May 12, 2026 •

edited

Loading